From e8c4b8338f0f34d09050c3d4096d88498ce4172d Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@gnome.org>
Date: Thu, 30 Apr 2020 16:08:37 +0100
Subject: [PATCH] docs: Mention blocking functions in the migration guide

Link to how to make a dialog modal, and to the response signal.
---
 docs/reference/gtk/migrating-3to4.xml | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/docs/reference/gtk/migrating-3to4.xml b/docs/reference/gtk/migrating-3to4.xml
index ee5bc5ecf9..32fa09d8bb 100644
--- a/docs/reference/gtk/migrating-3to4.xml
+++ b/docs/reference/gtk/migrating-3to4.xml
@@ -1254,5 +1254,24 @@
         emitted.
       </para>
     </section>
+
+    <section>
+      <title>Stop using blocking dialog functions</title>
+      <para>
+        GtkDialog, GtkNativeDialog, and GtkPrintOperation removed their
+        blocking API using nested main loops. Nested main loops present
+        re-entrancy issues and other hard to debug issues when coupled
+        with other event sources (IPC, accessibility, network operations)
+        that are not under the toolkit or the application developer's
+        control. Additionally, "stop-the-world" functions do not fit
+        the event-driven programming model of GTK.
+      </para>
+      <para>
+        You can replace calls to <function>gtk_dialog_run()</function>
+        by specifying that the #GtkDialog must be modal using
+        gtk_window_set_modal() or the %GTK_DIALOG_MODAL flag, and
+        connecting to the #GtkDialog::response signal.
+      </para>
+    </section>
   </section>
 </chapter>
-- 
2.30.2